array.h File Reference

• Array class

More...

#include "common.h"

Include dependency graph for array.h:

Go to the source code of this file.

Classes
struct	mrb_shared_array
struct	RArray

Macros
#define	MRB_ARY_EMBED_LEN_MAX   ((mrb_int)(sizeof(void*)*3/sizeof(mrb_value)))
#define	mrb_ary_ptr(v)
#define	mrb_ary_value(p)
#define	RARRAY(v)
#define	MRB_ARY_EMBED_MASK   7
#define	ARY_EMBED_P(a)
#define	ARY_UNSET_EMBED_FLAG(a)
#define	ARY_EMBED_LEN(a)
#define	ARY_SET_EMBED_LEN(a, len)
#define	ARY_EMBED_PTR(a)
#define	ARY_LEN(a)
#define	ARY_PTR(a)
#define	RARRAY_LEN(a)
#define	RARRAY_PTR(a)
#define	RARRAY_GETMEM(a, ptr, len)
#define	ARY_SET_LEN(a, n)
#define	ARY_CAPA(a)
#define	MRB_ARY_SHARED   256
#define	ARY_SHARED_P(a)
#define	ARY_SET_SHARED_FLAG(a)
#define	ARY_UNSET_SHARED_FLAG(a)
#define	ARY_GETMEM(a, ptr, len)
#define	mrb_ary_ref(mrb, ary, n)

Typedefs
typedef struct mrb_shared_array	mrb_shared_array

Functions
	mrb_static_assert (((mrb_int)(sizeof(void *) *3/sizeof(mrb_value))) > 0, "MRB_ARY_EMBED_LEN_MAX > 0")
void	mrb_ary_modify (mrb_state *, struct RArray *)
	Prepares an array for modification.
mrb_value	mrb_ary_dup (mrb_state *, mrb_value ary)
mrb_value	mrb_ary_make_shared_copy (mrb_state *, mrb_value ary)
mrb_value	mrb_ary_new_capa (mrb_state *, mrb_int)
	Creates a new array with a specified initial capacity.
mrb_value	mrb_ary_new (mrb_state *mrb)
	Creates a new, empty array.
mrb_value	mrb_ary_new_from_values (mrb_state *mrb, mrb_int size, const mrb_value *vals)
	Creates a new array initialized with a given sequence of values.
mrb_value	mrb_assoc_new (mrb_state *mrb, mrb_value car, mrb_value cdr)
	Creates a new array of size 2, typically used to represent an association (key-value pair).
void	mrb_ary_concat (mrb_state *mrb, mrb_value self, mrb_value other)
	Concatenates one array to another.
mrb_value	mrb_ary_splat (mrb_state *mrb, mrb_value value)
	Creates a new array from a given value, performing a "splat" operation.
void	mrb_ary_push (mrb_state *mrb, mrb_value array, mrb_value value)
	Pushes an element onto the end of an array.
mrb_value	mrb_ary_pop (mrb_state *mrb, mrb_value ary)
	Removes and returns the last element from an array.
void	mrb_ary_set (mrb_state *mrb, mrb_value ary, mrb_int n, mrb_value val)
	Sets the element at a given index in an array.
void	mrb_ary_replace (mrb_state *mrb, mrb_value self, mrb_value other)
	Replaces the contents of an array with the contents of another array.
mrb_value	mrb_ary_unshift (mrb_state *mrb, mrb_value self, mrb_value item)
	Prepends an element to the beginning of an array.
mrb_value	mrb_ary_entry (mrb_value ary, mrb_int offset)
	Retrieves an element from an array at a specific index.
mrb_value	mrb_ary_splice (mrb_state *mrb, mrb_value self, mrb_int head, mrb_int len, mrb_value rpl)
	Replaces a portion of an array with elements from another array or a single value.
mrb_value	mrb_ary_shift (mrb_state *mrb, mrb_value self)
	Removes and returns the first element from an array.
mrb_value	mrb_ary_clear (mrb_state *mrb, mrb_value self)
	Removes all elements from an array, making it empty.
mrb_value	mrb_ary_join (mrb_state *mrb, mrb_value ary, mrb_value sep)
	Joins the elements of an array into a string, separated by a given separator.
mrb_value	mrb_ary_resize (mrb_state *mrb, mrb_value ary, mrb_int new_len)
	Resizes an array to a new length.

Detailed Description

• Array class

See Copyright Notice in mruby.h

Macro Definition Documentation

ARY_CAPA

#define ARY_CAPA

(

a

)

Value:

(ARY_EMBED_P(a)?MRB_ARY_EMBED_LEN_MAX:(a)->as.heap.aux.capa)

ARY_EMBED_LEN

#define ARY_EMBED_LEN

(

a

)

Value:

((mrb_int)(((a)->flags & MRB_ARY_EMBED_MASK) - 1))

ARY_EMBED_P

#define ARY_EMBED_P

(

a

)

Value:

((a)->flags & MRB_ARY_EMBED_MASK)

ARY_EMBED_PTR

#define ARY_EMBED_PTR

(

a

)

Value:

((a)->as.ary)

ARY_GETMEM

#define ARY_GETMEM	(		a,
			ptr,
			len )

Value:

  do { \
  struct RArray *MRB_UNIQNAME(_a_) = (a); \
  if (ARY_EMBED_P(MRB_UNIQNAME(_a_))) { \
    (len) = ARY_EMBED_LEN(MRB_UNIQNAME(_a_)); \
    (ptr) = ARY_EMBED_PTR(MRB_UNIQNAME(_a_)); \
  } \
  else { \
    (len) = MRB_UNIQNAME(_a_)->as.heap.len; \
    (ptr) = MRB_UNIQNAME(_a_)->as.heap.ptr; \
  } \
} while (0)

ARY_LEN

#define ARY_LEN

(

a

)

Value:

(ARY_EMBED_P(a)?ARY_EMBED_LEN(a):(mrb_int)(a)->as.heap.len)

ARY_PTR

#define ARY_PTR

(

a

)

Value:

(ARY_EMBED_P(a)?ARY_EMBED_PTR(a):(a)->as.heap.ptr)

ARY_SET_EMBED_LEN

#define ARY_SET_EMBED_LEN	(		a,
			len )

Value:

((a)->flags = ((a)->flags&~MRB_ARY_EMBED_MASK) | ((uint32_t)(len) + 1))

ARY_SET_LEN

#define ARY_SET_LEN	(		a,
			n )

Value:

  do {\
  if (ARY_EMBED_P(a)) {\
    mrb_assert((n) <= MRB_ARY_EMBED_LEN_MAX); \
    ARY_SET_EMBED_LEN(a,n);\
  }\
  else\
    (a)->as.heap.len = (n);\
} while (0)

ARY_SET_SHARED_FLAG

#define ARY_SET_SHARED_FLAG

(

a

)

Value:

((a)->flags |= MRB_ARY_SHARED)

ARY_SHARED_P

#define ARY_SHARED_P

(

a

)

Value:

((a)->flags & MRB_ARY_SHARED)

ARY_UNSET_EMBED_FLAG

#define ARY_UNSET_EMBED_FLAG

(

a

)

Value:

((a)->flags &= ~(MRB_ARY_EMBED_MASK))

ARY_UNSET_SHARED_FLAG

#define ARY_UNSET_SHARED_FLAG

(

a

)

Value:

((a)->flags &= ~MRB_ARY_SHARED)

mrb_ary_ptr

#define mrb_ary_ptr

(

v

)

Value:

((struct RArray*)(mrb_ptr(v)))

mrb_ary_ref

#define mrb_ary_ref	(		mrb,
			ary,
			n )

Value:

mrb_ary_entry(ary, n)

mrb_ary_value

#define mrb_ary_value

(

p

)

Value:

mrb_obj_value((void*)(p))

RARRAY

#define RARRAY

(

v

)

Value:

((struct RArray*)(mrb_ptr(v)))

RARRAY_GETMEM

#define RARRAY_GETMEM	(		a,
			ptr,
			len )

Value:

ARY_GETMEM(RARRAY(a), ptr, len)

RARRAY_LEN

#define RARRAY_LEN

(

a

)

Value:

ARY_LEN(RARRAY(a))

RARRAY_PTR

#define RARRAY_PTR

(

a

)

Value:

ARY_PTR(RARRAY(a))

Function Documentation

mrb_ary_clear()

mrb_value mrb_ary_clear ( mrb_state * mrb, mrb_value self )

extern

Removes all elements from an array, making it empty.

This function modifies the array in place.

Parameters

mrb	The mruby state.
self	The array (mrb_value) to clear.

Returns

The cleared (now empty) array (the same mrb_value as self).

mrb_ary_concat()

void mrb_ary_concat ( mrb_state * mrb, mrb_value self, mrb_value other )

extern

Concatenates one array to another.

Appends all elements from the other array to the self array. This function modifies the self array in place.

Parameters

mrb	The mruby state.
self	The array (mrb_value) to which elements will be added.
other	The array (mrb_value) whose elements will be appended.

mrb_ary_entry()

mrb_value mrb_ary_entry ( mrb_value ary, mrb_int n )

extern

Retrieves an element from an array at a specific index.

This is a direct (unsafe) equivalent of RARRAY_PTR(ary)[n].

If n is negative, it counts from the end of the array. Returns nil if the index is out of bounds. This function does not perform a bounds check before accessing the element if the index is positive. Prefer using mrb_ary_ref for safe access or ensure n is within bounds.

Parameters

ary	The array (mrb_value) from which to retrieve the element.
n	The index of the element to retrieve.

Returns

The mrb_value at the specified index, or nil if out of bounds.

mrb_ary_join()

mrb_value mrb_ary_join ( mrb_state * mrb, mrb_value ary, mrb_value sep )

extern

Joins the elements of an array into a string, separated by a given separator.

Each element of ary is converted to a string. These strings are then concatenated, with the string representation of sep inserted between adjacent elements. If sep is nil, no separator is used. This function handles recursive array joins by raising an E_ARGUMENT_ERROR.

Parameters

mrb	The mruby state.
ary	The array (mrb_value) whose elements are to be joined.
sep	The separator (mrb_value) to use between elements. Can be nil.

Returns

A new mrb_value string representing the joined array elements.

mrb_ary_modify()

void mrb_ary_modify ( mrb_state * mrb, struct RArray * a )

extern

Prepares an array for modification.

This function ensures that the array is not frozen and is not shared. If the array is shared and has multiple references, this function will duplicate the array data to ensure that modifications do not affect other references. It also triggers a write barrier for the garbage collector.

Parameters

mrb	The mruby state.
a	A pointer to the RArray structure to modify.

mrb_ary_new()

mrb_value mrb_ary_new ( mrb_state * mrb )

extern

Creates a new, empty array.

This function is equivalent to calling mrb_ary_new_capa with a capacity of 0. The array will dynamically resize as elements are added.

Parameters

mrb	The mruby state.

Returns

A new mrb_value representing the created empty array.

mrb_ary_new_capa()

mrb_value mrb_ary_new_capa ( mrb_state * mrb, mrb_int capa )

extern

Creates a new array with a specified initial capacity.

This function allocates an array that can hold at least capa elements without needing to immediately reallocate memory. If capa is 0, it may still allocate a small default capacity.

Parameters

mrb	The mruby state.
capa	The initial capacity desired for the array.

Returns

A new mrb_value representing the created array.

mrb_ary_new_from_values()

mrb_value mrb_ary_new_from_values ( mrb_state * mrb, mrb_int size, const mrb_value * vals )

extern

Creates a new array initialized with a given sequence of values.

This function allocates an array and copies size elements from the vals pointer into the new array.

Parameters

mrb	The mruby state.
size	The number of values to initialize the array with.
vals	A pointer to an array of mrb_values to copy into the new array.

Returns

A new mrb_value representing the created array.

mrb_ary_pop()

mrb_value mrb_ary_pop ( mrb_state * mrb, mrb_value ary )

extern

Removes and returns the last element from an array.

If the array is empty, returns nil. This function modifies the array in place.

Parameters

mrb	The mruby state.
ary	The array (mrb_value) from which to pop the element.

Returns

The last element of the array, or nil if the array is empty.

mrb_ary_push()

void mrb_ary_push ( mrb_state * mrb, mrb_value ary, mrb_value elem )

extern

Pushes an element onto the end of an array.

This function appends elem to the ary array, increasing its length by one. The array capacity may be expanded if necessary. This function modifies the array in place.

Parameters

mrb	The mruby state.
ary	The array (mrb_value) to push the element onto.
elem	The mrb_value to append to the array.

mrb_ary_replace()

void mrb_ary_replace ( mrb_state * mrb, mrb_value self, mrb_value other )

extern

Replaces the contents of an array with the contents of another array.

After this operation, the self array will contain the same elements as the other array. This function modifies the self array in place.

Parameters

mrb	The mruby state.
self	The array (mrb_value) whose contents will be replaced.
other	The array (mrb_value) from which to copy the elements.

mrb_ary_resize()

mrb_value mrb_ary_resize ( mrb_state * mrb, mrb_value ary, mrb_int new_len )

extern

Resizes an array to a new length.

If new_len is smaller than the current length, the array is truncated. If new_len is larger than the current length, the array is expanded, and new elements are filled with nil. This function modifies the array in place.

Parameters

mrb	The mruby state.
ary	The array (mrb_value) to resize.
new_len	The desired new length of the array.

Returns

The resized array (the same mrb_value as ary).

mrb_ary_set()

void mrb_ary_set ( mrb_state * mrb, mrb_value ary, mrb_int n, mrb_value val )

extern

Sets the element at a given index in an array.

If n is within the current bounds of the array, the element at that index is replaced with val. If n is beyond the current bounds, the array is expanded to accommodate the new element, and any intermediate elements are filled with nil. If n is negative, it counts from the end of the array. An IndexError is raised if a negative index points past the beginning of the array. This function modifies the array in place.

Parameters

mrb	The mruby state.
ary	The array (mrb_value) to modify.
n	The index at which to set the element.
val	The mrb_value to set at the specified index.

mrb_ary_shift()

mrb_value mrb_ary_shift ( mrb_state * mrb, mrb_value self )

extern

Removes and returns the first element from an array.

If the array is empty, returns nil. All other elements are shifted down by one index. This function modifies the array in place.

Parameters

mrb	The mruby state.
self	The array (mrb_value) from which to shift the element.

Returns

The first element of the array, or nil if the array is empty.

mrb_ary_splat()

mrb_value mrb_ary_splat ( mrb_state * mrb, mrb_value v )

extern

Creates a new array from a given value, performing a "splat" operation.

If v is already an array, a duplicate of v is returned. If v responds to to_a, it is called, and if the result is an array, a duplicate of that result is returned. If to_a returns nil or something other than an array, v itself is wrapped in a new, single-element array. Otherwise (if v is not an array and does not respond to to_a), v itself is wrapped in a new, single-element array.

Parameters

mrb	The mruby state.
v	The mrb_value to convert into an array.

Returns

A new mrb_value representing the "splatted" array.

mrb_ary_splice()

mrb_value mrb_ary_splice ( mrb_state * mrb, mrb_value ary, mrb_int head, mrb_int len, mrb_value rpl )

extern

Replaces a portion of an array with elements from another array or a single value.

Removes len elements from ary starting at head index, and inserts the elements from rpl (if rpl is an array) or rpl itself (if it's not an array) at that position. If head is negative, it counts from the end of the array. If len is negative, an IndexError is raised. If rpl is mrb_undef_p(), then the elements are removed without replacement. This function modifies the ary array in place.

Parameters

mrb	The mruby state.
ary	The array (mrb_value) to modify.
head	The starting index for the splice operation.
len	The number of elements to remove.
rpl	The mrb_value to insert (can be an array or a single value, or mrb_undef_p()).

Returns

The modified array (the same mrb_value as ary).

mrb_ary_unshift()

mrb_value mrb_ary_unshift ( mrb_state * mrb, mrb_value self, mrb_value item )

extern

Prepends an element to the beginning of an array.

This function adds item to the front of the self array, shifting all existing elements up by one index. The array capacity may be expanded if necessary. This function modifies the array in place.

Parameters

mrb	The mruby state.
self	The array (mrb_value) to unshift the element onto.
item	The mrb_value to prepend to the array.

Returns

The modified array (the same mrb_value as self).

mrb_assoc_new()

mrb_value mrb_assoc_new ( mrb_state * mrb, mrb_value car, mrb_value cdr )

extern

Creates a new array of size 2, typically used to represent an association (key-value pair).

The first element of the array is car (often the key), and the second element is cdr (often the value).

Parameters

mrb	The mruby state.
car	The first value to be placed in the array.
cdr	The second value to be placed in the array.

Returns

A new mrb_value representing the created 2-element array.